home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 August: Tool Chest / Dev.CD Aug 98 TC.toast / What's New? / Software Development Kits / Mac OS USB DDK / MacOS USB DDK 1.0b4 / NeptuneDDK / MacOS USB DDK Readme < prev    next >
Encoding:
Text File  |  1998-06-26  |  17.3 KB  |  453 lines  |  [ttro/ttxt]
  1.  
  2.  
  3.  
  4.  ***
  5.  ***       Universal Serial Bus™ (USB) for the MacOS
  6.  ***    MacOS USB 1.0b4 DDK Developer Release Notes
  7.  ***    Copyright 1998 Apple Computer, Inc.
  8.  ***
  9.  
  10.  
  11.  
  12.  Table of Contents:
  13. -------------------------------------------------------------
  14.  A Note on Participation
  15.  USB Fundamentals
  16.  Getting started with MacOS USB
  17.  Installing the MacOS USB Software
  18.  Using the MacOS USB DDK under MPW
  19.  Installing the MacOS USB DDK into MPW for the First Time  
  20.  Updating a Previously Installed Neptune DDK  for MPW
  21.  Using the MacOS USB DDK with MetroWerks CodeWarrior
  22.  Installing the MacOS USB DDK for CodeWarrior for the First Time  
  23.  Updating a Previously Installed MacOS USB DDK for CodeWarrior
  24.  Installing the MacOS USB Components onto your Target System
  25.  Description of Installed Files
  26.  Known Problems
  27.  Contact Information
  28. -------------------------------------------------------------
  29.  
  30.  
  31. A Note on Participation
  32. -----------------------
  33.  
  34. Early seeding is important to developers and Apple alike; however, in
  35. the past, we haven't received the level of feedback we'd expect for
  36. something you've told us is so important.
  37.  
  38. To ensure compatibility with USB, developers should not assume
  39. Apple will test their products internally. It's important that
  40. every developer test their products with this pre-release
  41. software and provide feedback on problems they encounter.
  42.  
  43. Two important guidelines:
  44.  
  45.     --  Provide feedback. This DDK is the first of it's kind for 
  46.         USB support on the Macintosh.  You may find that there is 
  47.         functionality which we have not provided, which you 
  48.         need to support your product.  There are known issues
  49.         which we have documented below.  However, other issues
  50.         are better addressed before the product is finalized.
  51.         This leads to the second guideline.
  52.  
  53.     --  Provide feedback as early as possible. The introduction
  54.         of the iMac draws near.  We will finalize the introductory
  55.         release of MacOS USB, shortly.  However, we
  56.         will carefully review all of your bug reports, and 
  57.         consider all of your comments and suggestions.  We will
  58.         update that USB product following the iMac introduction,
  59.         however, we do not have a schedule for the update at this 
  60.         time.
  61.  
  62.  
  63. USB Fundamentals
  64. ----------------
  65.  
  66. For the coming generation of Power Macintosh systems, USB is the 
  67. primary interface for connections to low to medium speed peripheral
  68. devices. There a numerous advantages for adopting the USB standard on
  69. Macintosh, and they are discussed in the "MacOS USB DDK API Reference
  70. Guide". On the future Macintosh systems there will be no ADB, 
  71. Serial Port, or SCSI connections. USB will be the primary port 
  72. for connecting peripheral devices to the Macintosh. 
  73.  
  74. Read the USB Software Development Guide located at the root level of
  75. the DDK to learn about developing for the MacOS USB implementation.
  76. The DDK provides the tools, interfaces, system files, and module 
  77. examples for you to start development of USB products
  78. for the Macintosh. 
  79.  
  80. WARNING:
  81.  
  82.     It is still possible there are significant bugs in this build of MacOS
  83.     USB. Do not risk critical data by exposing it to this
  84.     software. Do not install this software on a machine which is
  85.     critical to your business.
  86.  
  87. IMPORTANT:
  88.  
  89.     Do not build your final product release using the interface files
  90.     and libraries from this DDK. Watch the DDK web page mentioned
  91.     below for news on updates to this DDK, and for news on the
  92.     release of the final product.
  93.  
  94. Getting started with MacOS USB
  95. -----------------------------
  96.  
  97. As of the writing of this note, Power Macintosh Systems which have
  98. USB support built-in, are under development. Seed units for 
  99. Developers are limited and Apple will be unable to provide
  100. developments systems to all developers. To jump-start the 
  101. development process for MacOS USB, you can obtain a PCI 
  102. USB card from two sources - CMD Technology and OPTi. As other 
  103. sources for PCI USB cards become available, we will revise
  104. this readme to include them.
  105.  
  106. For CMD Technology, Inc, the web page is 
  107.  
  108.         <http://www.cmd.com/>.
  109.  
  110. For OPTi, the web page is
  111.  
  112.         <http://www.opti.com/html/usbsolutions.html>.
  113.  
  114. We advise you to obtain cards from both sources so that you can
  115. test on both cards to ensure maximum compatability.
  116.  
  117. With these cards, and the supplied software, you can start work on 
  118. developing your USB Modules to support your
  119. devices, along with the associated applications. The DDK provides 
  120. examples for both the MPW and MetroWerks CodeWarrior Pro
  121. environments. Please carefully, read the notes below, on how you 
  122. will need to configure your environment to build the example
  123. modules.
  124.  
  125.  
  126. Installing the MacOS USB Software
  127. ---------------------------------
  128.  
  129. To install the USB System Software components, drag copy the 
  130. contents of the folder
  131.  
  132. :NeptuneDDK:For System Folder (Apple Built): 
  133.  
  134. to the Extensions folder, and reboot.
  135.  
  136.  
  137. Important Notes on Installation and Use of this Beta DDK software
  138. ------------------------------------------------------------
  139.  
  140. This DDK will let you look at the sources to some working class 
  141. drivers, build the examples, and develop & build your own code.
  142.  
  143. Please remember that these driver samples are Copyright Apple 
  144. Computer, Inc.. You may use the supplied code to develop Class 
  145. Drivers for your devices. As for publishing the source code, please
  146. check first with the MacOS USB DDK License agreement, included
  147. in this DDK.
  148.  
  149. The current driver samples may, or may not, reflect the final
  150. state of the art of driver writing for USB in the MacOS.  
  151. They are only intended to show you working drivers, and we 
  152. will be revising them as we get closer to shipping product.
  153.  
  154. While not extensively tested (by the development team), 
  155. the sample sources have been tweaked slightly to make builds 
  156. under CodeWarrior some what less problematic. This is going 
  157. to be an incremental process, so please be patient as we 
  158. improve this process.
  159.  
  160.  
  161. Using the MacOS USB DDK under MPW
  162. ---------------------------------
  163.  
  164. The following are guidelines for using this DDK with the 
  165. MPW programming environment.
  166.  
  167. 1. You must have MPW 3.4.2 (or later) from ETO 23. 
  168.  
  169.    We are not supporting the use of any versions of MPW
  170.    previous to v3.4.2.
  171.    
  172. 2. You must use the Universal Interfaces&Libraries 3.1 from the 
  173.    Apple ftp site. Follow the instructions which are provided
  174.    with the Interfaces&Libraries download to upgrade the 
  175.    MPW programming environment.  The URL for the Developer
  176.    Development Kits web page is
  177.    
  178.    <http://developer.apple.com/sdk/>
  179.    
  180. 3. You should update the USB.h file in the Universal Interfaces 
  181.    CIncludes folder with the USB.h file from the NeptuneDDK 
  182.    Folder.
  183.           
  184. It is highly recommend that you use one Macintosh for coding 
  185.    purposes and one Mac (aka "Target" system) for 
  186.    checkout/testing purposes.
  187.  
  188. 4. Within MPW, there will be the NeptuneDDK menu.  Choose
  189.    the desired sample module to build from the "Select Example"
  190.    menu item.  Use the "Build Driver or Example" menu item
  191.    to build the example file.  The driver modules which you 
  192.    build will be placed into the "NeptuneDDK:Targets:"
  193.    folder.
  194.  
  195.  
  196. Installing the MacOS USB DDK into MPW for the First Time
  197. --------------------------------------------------------
  198.  
  199. 1. Drop the UserStartup•NeptuneDDK into your MPW folder.  
  200.  
  201. 2. Ensure that the name of the development system's Neptune DDK
  202.    folder is NeptuneDDK. The MPW scripts supplied in this DDK 
  203.    will fail if the folder is named differently.
  204.    
  205.    It has been reported that the NeptuneDDK MPW startup script 
  206.    doesn't handle spaces that are part of the complete pathname
  207.    correctly. This should be corrected in a later release.
  208.  
  209. 3. Launch MPW
  210.  
  211.    You'll be prompted to point to  *YOUR* DDK folder.  That is, 
  212.    the NeptuneDDK folder on your hard drive, not a projector 
  213.    database on a server.
  214.  
  215. 4. Drag the "For System Folder" items go into your "target" 
  216.    system's system folder, not the development system's system 
  217.    folder!  The development system only needs the contents of the
  218.    DDK and MPW folders.
  219.  
  220.  
  221. Updating a Previously Installed Neptune DDK for MPW
  222. ---------------------------------------------------
  223.  
  224. 1. Drop the UserStartup•NeptuneDDK into your MPW folder.  This 
  225.    file may have changed from the last release of the DDK
  226.    
  227. 2. Drag *your* folders from inside the "Drivers" folder 
  228.    from the old DDK to the Driver folder of the new Neptune DDK 
  229.    folder.
  230.    
  231. 3. Change the name of the OLD NeptuneDDK folder to something 
  232.    like "Old NeptuneDDK"  
  233.  
  234. 4. Change the name of the *new* Neptune DDK folder to match 
  235.    *exactly* what your old NeptuneDDK folder was called.
  236.    
  237. 5. If you don't get the name exactly right, then MPW will ask 
  238.    you to locate the folder the next time you start it.  
  239.    Be warned:  Spaces in the DDK folder name are NOT
  240.    recommended.
  241.    
  242. 6. Start MPW.  Any drivers you've moved from the old DDK to 
  243.    the new DDK's "Drivers" folder will automatically appear 
  244.    in the NeptuneDDK Drivers submenu.
  245.  
  246.  
  247. Using the MacOS USB DDK with MetroWerks CodeWarrior
  248. ---------------------------------------------------
  249.  
  250. We have supplied MetroWerks CodeWarrior project files for
  251. all of the USB Modules code examples. All of the project
  252. files were created using CodeWarrior Pro 1, IDE 2.0. The 
  253. project files are also compatible with CodeWarrior Pro IDE 
  254. 2.1 and 3.0.
  255.  
  256. For the CodeWarrior IDE environments v2.0 - v3.0, you must use
  257. the Universal Interface & Libraries v3.1. The examples will
  258. not build using the interfaces supplied with the CodeWarrior
  259. v.2 - v3.0 environments. The URL for the Developer Development
  260. Kits web page is
  261.    
  262.    <http://developer.apple.com/sdk/>
  263.  
  264. As mentioned for MPW, it is highly recommend that you use 
  265. one Macintosh for coding purposes and one Mac (aka "Target"
  266. system) for checkout/testing purposes.
  267.  
  268. The supplied project files will place the built drivers
  269. and extensions into the Target folder of the DDK.
  270.  
  271.  
  272. Installing the MacOS USB DDK for CodeWArrior for the First Time
  273. -----------------------------------------------------------
  274.  
  275. 1. You can place the NeptuneDDK anywhere on your development
  276.    system for the CodeWarrior environment. The access paths
  277.    for the project files are project and compiler relative.
  278.    If you move the examples folders out of the DDK, you must
  279.    fix the access paths so that the sources can be found.
  280.   
  281. 2. Ensure that the CodeWarrior IDE environment has the 
  282.    Universal Interfaces and Libraries 3.1 installed. The
  283.    download file from the DDK website includes instructions
  284.    for upgrading your CodeWarrior environment. Note that if
  285.    you upgrade your interfaces, you will also need to 
  286.    upgrade your precompiled headers. The supplied CodeWarrior
  287.    project files do not use precompiled headers.
  288.  
  289. 3. Copy the USB.h file included in this SDK to the 
  290.    ":MacOS Support:Headers:Universal Headers:" folder.
  291.    
  292.  
  293. Updating a Previously Installed MacOS USB DDK for CodeWarrior
  294. -------------------------------------------------------------
  295.  
  296. 1. Copy the USB.h file included in this SDK to the 
  297.    ":MacOS Support:Headers:Universal Headers:" folder. Do not
  298.    use the USB.h header file from an earlier USB DDK with the
  299.    supplied project files, as the examples may not build.
  300.  
  301.  
  302. Installing the MacOS USB Components onto your Target System
  303. -----------------------------------------------------------
  304.  
  305. IMPORTANT NOTE: Do not install the USB Extensions and Libraries
  306. into the System Folder of a CPU that has the USB Support integrated
  307. into the System ROM.
  308.  
  309. 1. Delete any existing files prefixed with "USB" from your system
  310.    folder's extension folder.  This applies only if an earlier 
  311.    pre-release version of MacOS USB DDK software had been 
  312.    installed.
  313.  
  314. 2. Drag all the files from the 'For System Folder (Apple Built)' 
  315.    folder to the System Folder (ultimately destined for the 
  316.    system folder's extension folder). 
  317.  
  318. 3. Verify that all of the files that you dragged from the 'For 
  319.    System Folder (SCM Built)' folder were placed in the system 
  320.    folder's extensions folder.
  321.    
  322.    
  323. Description of Installed Files
  324. --------------------------
  325. Files in the 'For System Folder (SCM Built)' folder:
  326. Files:                              Description:
  327. USBCompositeDriver      A class driver which is loaded for class 0 &
  328.                                       and subclass 0 devices (typically keyboards &
  329.                                       mice, although a few printers & modems appear as
  330.                                       composite class devices).
  331.                             
  332. USBFamilyExpert           The INIT (actually an 'expt') portion of the Family 
  333.                                       Expert. Loaded prior to the INIT parade, it starts 
  334.                                       the 'find a USB bus (ie. UIM driver), loads the
  335.                                       hub driver (for the root hub), and starts
  336.                                       the hub driver running.  Once running, the
  337.                                       hub driver locates devices attached to the
  338.                                       port and asks the FamilyExpertLib to load
  339.                                       drivers for the devices connected to the
  340.                                       hub's ports.
  341.  
  342. USBHubDriver0 &           The Hub driver for the root hub, the Apple USB 
  343. USBHubDriver1              keyboard's hub, and some 3rd party hubs.
  344.  
  345. USBKeyboardModule       The HID Module loaded for a keyboard
  346.                                       interface (typically in a compound device)
  347.                             
  348. USBMouseModule            A HID Module loaded for a mouse interface
  349.                                       (typically in a compound device).
  350.                             
  351. USBOpenHCIDriver         The HAL (Hardware Abstraction Layer), also
  352.                                       known as the "UIM" (USB Interface Module).
  353.                                       This driver provides an abstracted interface
  354.                                       to the OpenHCI host controllers on Mac
  355.                                       motherboards and PCI controller cards.
  356.                             
  357. USBPrintDriver              A Printing Class Driver for experimentation
  358.                                       purposes.  Printing WILL NOT be functional
  359.                                       simply with the addition of this file.  The
  360.                                       chooser extension needed for USB printing
  361.                                       is still in development and has not yet
  362.                                       been released.
  363.          
  364.  
  365. Known Problems
  366. --------------
  367.  
  368. There will, of course, be bugs in early builds of the MacOS USB DDK. 
  369. In this section, rather than attempt to list all known bugs, we will 
  370. attempt to alert you to entire components which are not functional 
  371. or major functionality within a component which you should avoid.
  372.  
  373.   - The MacOS USB DDK v1.0 does not provide any isochronous
  374.     support. Isochronous support will be implemented in a 
  375.     future release of the MacOS USB DDK.
  376.     
  377.   - While you can hot plug and unplug devices and replug them, 
  378.     there is a known problem that after 4 - 5 hot plug/unplug/hot
  379.     replugs, the device may not register, due to a memory leak.
  380.  
  381.   - This version of the DDK does not include a document which completely 
  382.     describes the software design and implementation of a USB class driver.
  383.     In a coming release of the DDK, this issue will be addressed.
  384.  
  385.   - We are investigating problems with the implementation of Bulk Transfer
  386.     which manifests itself as lost data. If you encounter problems with
  387.     Bulk Transfer, we advise you to try replicating the problem with a
  388.     PCI USB card from a different vendor.
  389.  
  390.   - Once you plug in the first HID device that is not a keyboard or mouse
  391.     device, no other HID device (other than a keyboard or mouse) will be
  392.     recognized, even if you unplug and replug the same HID device. The
  393.     workaround is to reboot the system.
  394.  
  395.   - In a future release of this DDK, we will include 2 additional example
  396.      modules - a print class module, and a universal HID module which supports
  397.      USB game devices via the Game Sprocket's InputsprocketLib. 
  398.  
  399. Contact Information
  400. -------------------
  401.  
  402.   MacOS USB DDK Upgrades and latest information:
  403.     
  404.     This DDK is not final. Check the Developer Development Kits web page for
  405.         upgrades to the MacOS USB DDK. The web page is
  406.         
  407.         <http://developer.apple.com/sdk/>
  408.  
  409.     For the latest information on MacOS USB, check the MacOS USB web page.
  410.     The web page is
  411.  
  412.     <http://usb.apple.com>
  413.  
  414.   For Bug Reports:
  415.  
  416.     To ensure the appropriate data is collected, please use the Bug Reporter  
  417.     to send us your bug reports. The Bug Reporter can be found at: 
  418.  
  419.     <http://developer.apple.com/bugreporter>
  420.  
  421.     When reporting problems, please include the machine configuration, 
  422.     including the vendor of the PCI USB card which you have tested with.
  423.  
  424.   For Technical Questions:
  425.  
  426.     Contact Worldwide Developer with purchased development-level technical 
  427.     support incidents at
  428.  
  429.     dts@apple.com
  430.  
  431.     Technical support incidents are bundled in our Premier and Select 
  432.     Developer programs. For information about joining our programs, 
  433.     please visit our Apple Developer Connection web site at 
  434.  
  435.     http://developer.apple.com/programs. 
  436.  
  437.     If you have never purchased a technical support incident and would like 
  438.     to find out how to do so, please visit the following site: 
  439.  
  440.     http://developer.apple.com/programs/techsupport.html . 
  441.  
  442.     
  443.   Comments, Suggestions and Enhancement Requests
  444.  
  445.     Please send all comments and suggestions regarding the MacOS USB DDK to
  446.     
  447.     usb@apple.com
  448.  
  449.     All email sent to this address will be read, however, we will not be to
  450.     respond to all of your comments and suggestions.
  451.  
  452.         
  453.